Floatplane REST API (3.8.9)

Download OpenAPI specification:Download

URL: https://github.com/Jman012/FloatplaneAPI/ License: MIT

Homepage: https://jman012.github.io/FloatplaneAPIDocs

This document describes the REST API layer of https://www.floatplane.com, a content creation and video streaming website created by Floatplane Media Inc. and Linus Media Group, where users can support their favorite creates via paid subscriptions in order to watch their video and livestream content in higher quality and other perks.

While this document contains stubs for all of the Floatplane APIs for this version, many are not filled out because they are related only to content creation, moderation, or administration and are not needed for regular use. These have "TODO" as the description, and are automatically removed before document generation. If you are viewing the "Trimmed" version of this document, they have been removed for brevity.

API Object Organization

Users and Creators exist on Floatplane at the highest level
- The highest-level object in Floatplane is the Creator. This is an entity, such as Linus Tech Tips, that produces media for Users.
A Creator owns one or more Subscription Plans
A User can view a Creator's Content if they are subscribed to them
A Creator publishes Content, in the form of Blog Posts
- Content is produced by Creators, and show up for subscribed Users to view when it is released. A piece of Content is meant to be generic, and may contain different types of sub-Content. Currently, the only type is a Blog Post.
- A Blog Post is the main type of Content that a Creator produces. Blog Posts are how a Creator can share text and/or media attachments with their subscribers.
A Blog Post is comprised of one or more of: video, audio, picture, or gallery Attachments
- A media Attachment may be: video, audio, picture, gallery. Attachments are a part of Blog Posts, and are in a particular order.
A Creator may also have a single Livestream

API Flow

As of Floatplane version 3.5.1, these are the recommended endpoints to use for normal operations.

Login
1. /api/v3/auth/captcha/info - Get captcha information
2. /api/v2/auth/login - Login with username, password, and optional captcha token
3. /api/v2/auth/checkFor2faLogin - Optionally provide 2FA token to complete login
4. /api/v2/auth/logout - Logout at a later point in time
Home page
1. /api/v3/user/subscriptions - Get the user's active subscriptions
2. /api/v3/content/creator/list - Using the subscriptions, show a home page with content from all subscriptions
  1. Supply all creator identifiers from the subscriptions
  2. This should be paginated
3. /api/v2/creator/info - Also show a list of creators that the user can select
  1. Note that this can search and return multiple creators. The V3 version only works for a single creator at a time.
Creator page
1. /api/v3/creator/info - Get more details for the creator to display, including if livestreams are available
2. /api/v3/content/creator - Show recent content by the creator
3. /api/v2/plan/info - Show available plans the user can subscribe to for the creator
Content page
1. /api/v3/content/post - Show more detailed information about a piece of content, including text description, available attachments, metadata, interactions, etc.
2. /api/v3/content/related - List some related content for the user to watch next
3. /api/v3/comment - Load comments for the content for the user to read
  1. There are several more comment APIs to post, like, dislike, etc.
4. /api/v2/user/ban/status - Determine if the user is banned from this creator
5. /api/v3/content/{video|audio|picture|gallery} - Load the attached media for the post. This is usually video, but audio, pictures, and galleries are also available.
6. /api/v2/cdn/delivery - For video and audio, this is required to get the information to stream or download the content in media players
Livestream
1. /api/v2/cdn/delivery - Using the type "livestream" to load the livestream media in a media player
2. wss://chat.floatplane.com/sails.io/?... - To connect to the livestream chat over websocket. TODO: Map out the WebSocket API.
User Profile
1. /api/v3/user/self - Display username, name, email, and profile pictures

API Organization

The organization of APIs into categories in this document are reflected from the internal organization of the Floatplane website bundled code, from frontend.floatplane.com/{version}/vendor.js. This is in order to use the best organization from the original developers' point of view.

For instance, Floatplane's authentication endpoints are organized into Auth.v2.login(...), Auth.v2.logout(), and Auth.v3.getCaptchaInfo(). A limitation in OpenAPI is the lack of nested tagging/structure, so this document splits Auth into AuthV2 and AuthV3 to emulate the nested structure.

Notes

Note that the Floatplane API does support the use of ETags for retrieving some information, such as retrieving information about creators, users, etc. Expect an HTTP 304 if the content has not changed, and to re-use cached responses. This is useful to ease the strain on Floatplane's API server.

The date-time format used by Floatplane API is not standard ISO 8601 format. The dates/times given by Floatplane include milliseconds. Depending on your code generator, you may need to override the date-time format to something similar to yyyy-MM-dd'T'HH:mm:ss.SSSZ, for both encoding and decoding.

Authentication

CookieAuth

Authentication and authorization to Floatplane API calls is governed by the sails.sid HTTP Cookie. To obtain this cookie, you must authenticate to /api/v2/auth/login.

When dealing with cookies in native applications (not via a website inside of a browser), please keep in mind that some languages/libraries may keep cookies across requests by default, and some may not. For instance, in Swift the URLSession.shared object with default configuration will automatically track and persist cookies across requests.

Security Scheme Type	API Key
Cookie parameter name:	sails.sid

ActivationV2

Activate new user accounts and confirming activation via email.

Confirm Email

TODO

username required	string
password required	string
captchaToken	string The Google Recaptcha v2/v3 token to verify the request. On web browsers, this is required. For mobile or TV applications, this is not required only if the User-Agent indicates so (e.g., if the User-Agent contains "CFNetwork" in its value). Otherwise, the application would have to supply a valid captcha token, which can be difficult to obtain dynamically in some scenarios.

type required	string Enum: "vod" "aod" "live" "download" Used to determine which kind of retrieval method is requested for the video. VOD = stream a Video On Demand AOD = stream Audio On Demand Live = Livestream the content Download = Download the content for the user to play later.
guid	string The GUID of the attachment for a post, retrievable from the `videoAttachments` or `audioAttachments` object. Required when `type` is `vod`, `aod`, or `download`. Note: either this or `creator` must be supplied.
creator	string The GUID of the creator for a livestream, retrievable from `CreatorModelV2.id`. Required when `type` is `live`. Note: either this or `guid` must be supplied.

paymentProcessor required	string
subPaymentProcessor required	string

creator required	string
property required	string Enum: "contentEmail" "contentFirebase" Use `contentEmail` for email notifications, and `contentFirebase` for push notifications.
newValue required	boolean

blogPost required	string The GUID of the blogPost the comment should be posted to.
text required	string The text of the comment being posted.

blogPost required	string Which blog post to retrieve comments for.
limit required	integer The maximum number of comments to return. This should be set to 20 by default.
fetchAfter	string When loading more comments on a blog post, this is used to determine which which comments to skip. This is a GUID of the last comment from the previous call to `getComments`.

comment required	string The identifer of the comment from which to retrieve replies.
blogPost required	string The identifer of the blog post the `comment` belongs to.
limit required	integer How many replies to retrieve.
rid required	string The identifer of the last reply in the reply chain.

comment required	string The GUID of the comment being liked.
blogPost required	string The GUID of the post the comment is on.

id required	string The GUID of the creator to retrieve posts from.
limit required	integer [ 1 .. 20 ] The maximum number of posts to return.
fetchAfter	integer The number of posts to skip. Usually a multiple of `limit`, to get the next "page" of results.
search	string Search filter to look for specific posts.
tags	Array of strings An array of tags to search against, possibly in addition to `search`.

ids required	Array of strings The GUID(s) of the creator(s) to retrieve posts from.
limit required	integer >= 1 The maximum number of posts to retrieve.
	Array of objects (ContentCreatorListLastItems) For pagination, this is used to determine which posts to skip. There should be one `fetchAfter` object for each creator in `ids`. The `moreFetchable` in the request, and all of the data, comes from the `ContentCreatorListV3Response`.

contentType required	string Value: "blogPost"
id required	string

Floatplane REST API (3.8.9)

API Object Organization

API Flow

API Organization

Notes

Authentication

CookieAuth

ActivationV2

Confirm Email

Authorizations:

Responses

Response samples

Request Activation Email

Authorizations:

Responses

Response samples

ACP_CreatorAgreementV2

List Creator Agreement

Authorizations:

Responses

Response samples

Get Creator Agreement

Authorizations:

Responses

Response samples

Edit Creator Agreement

Authorizations:

Responses

Response samples

ACP_CreatorV2

Get Creator List

Authorizations:

Responses

Response samples

Get Creator Details

Authorizations:

Responses

Response samples

Get Subscription Plan List

Authorizations:

Responses

Response samples

Check Creator Url Available

Authorizations:

Responses

Response samples

Get Creator Categories

Authorizations:

Responses

Response samples

Create Creator

Authorizations:

Responses

Response samples

Upload Cover

Authorizations:

Responses

Response samples

Get Creators Titles

Authorizations:

Responses

Response samples

Update Creator

Authorizations:

Responses

Response samples

Update Creator Subscription Plan

Authorizations:

Responses

Response samples

Upload Card

Authorizations:

Responses

Response samples

Upload Icon

Authorizations:

Responses

Response samples

ACP_CreatorV3

Get Creator Invite Code List